---
title: Scroll Plugin
description: Provides the <Scroller /> component and hooks for page layout, virtualization, and navigation.
searchable: true
---

# Scroll Plugin

The Scroll Plugin is a foundational plugin responsible for page layout, virtualization, and navigation. It provides the essential `<Scroller />` component, which intelligently renders only the visible pages to ensure high performance, and the `useScroll` hook for building page navigation controls.

## Installation

This plugin depends on the `Viewport` plugin. You must install both packages.

```sh npm2yarn
npm install @embedpdf/plugin-scroll @embedpdf/plugin-viewport
````

## Registration

Import `ScrollPluginPackage` and its `Viewport` dependency, and add them to the `plugins` array.

```tsx {5, 16-19}
import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/react'
import { ScrollPluginPackage, ScrollStrategy } from '@embedpdf/plugin-scroll/react'

const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(RenderPluginPackage),

  // Register dependencies first
  createPluginRegistration(ViewportPluginPackage),

  // Register and configure the scroll plugin
  createPluginRegistration(ScrollPluginPackage, {
    strategy: ScrollStrategy.Vertical, // or Horizontal
    initialPage: 1,
  }),
]
```

## Usage

The plugin provides the `<Scroller />` component for rendering pages and the `useScroll` hook for navigation.

### The `<Scroller />` and `renderPage` Prop

The `<Scroller />` component is the heart of the layout system. It must be placed inside a `<Viewport />`.

Crucially, the `<Scroller />` does not render pages itself. Instead, it calculates *which* pages should be visible and calls the function you provide to its `renderPage` prop for each one. This gives you complete control over the content of each page placeholder.

```tsx {4-5, 10-11}
import { RenderLayer } from '@embedpdf/plugin-render/react';

// ...
<Scroller
  renderPage={({ pageIndex, width, height, scale }) => (
    // This function is called for each visible page
    <div style={{ width, height, position: 'relative' }}>
      <RenderLayer pageIndex={pageIndex} scale={scale} />
    </div>
  )}
/>
```

### Page Navigation

The `useScroll` hook provides everything you need to build a page navigation UI. It returns a `provides` object with action methods and a `state` object with reactive data like the current page number.

```tsx {1,4, 8-9}
import { useScroll } from '@embedpdf/plugin-scroll/react';

const PageControls = () => {
  const { provides: scroll, state } = useScroll();

  return (
    <div>
      <span>Page {state.currentPage} of {state.totalPages}</span>
      <button onClick={() => scroll?.scrollToNextPage()}>Next</button>
    </div>
  );
};
```

## Live Example

This example features a complete page navigation component that allows jumping to a specific page and moving forward or backward.

import { PDFViewer } from '../code-examples/scroll-example';

<PDFViewer />

## API Reference

### Configuration (`ScrollPluginConfig`)

| Option | Type | Description |
| :--- | :--- | :--- |
| **`strategy`** | `ScrollStrategy` | Sets the scroll direction. Can be `ScrollStrategy.Vertical` or `ScrollStrategy.Horizontal`. <br />**Default**: `ScrollStrategy.Vertical` |
| **`pageGap`** | `number` | The space in pixels between pages or spreads. <br />**Default**: `10` |
| **`initialPage`** | `number` | The 1-based page number to scroll to when a document first loads. |
| **`bufferSize`** | `number`| The number of pages to render outside the visible area for a smoother scrolling experience. <br/>**Default**: `2` |

### Component: `<Scroller />`

The virtualized container that lays out pages.

| Prop | Type | Description |
| :--- | :--- | :--- |
| **`renderPage`** | `(props) => ReactNode` | **(Required)** A function that returns the content for a single page. It receives an object with page layout data like `pageIndex`, `width`, `height`, and `scale`. |

### Hook: `useScroll()`

A convenience hook for building page navigation UIs. It returns an object containing a `provides` object for actions and a `state` object for reactive data.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`provides`** | `ScrollCapability \| null` | An object with methods to control scrolling and navigation. `null` if the plugin is not ready. |
| **`state`** | `object` | An object containing the current reactive scroll state. |

#### `state` Properties

| Property | Type | Description |
| :--- | :--- | :--- |
| **`currentPage`** | `number` | The current page number that is most visible in the viewport. |
| **`totalPages`** | `number` | The total number of pages in the document. |

#### `provides` Methods (`ScrollCapability`)

| Method | Description |
| :--- | :--- |
| **`scrollToPage(options)`** | Scrolls to a specific page. The `options` object takes a `pageNumber` and optional `behavior: 'smooth'`. |
| **`scrollToNextPage()`** | Scrolls to the next page or spread. |
| **`scrollToPreviousPage()`** | Scrolls to the previous page or spread. |